其他
为啥要放弃 okhttp、httpClient，因为这款神器足矣，贼爽~
点击关注下方公众号，Java面试资料 都在这里
来源：https://juejin.cn/post/6898485806587969544
项目地址：https://github.com/LianjiaTech/retrofit-spring-boot-starter
# 前言
Retrofit是适用于Android和Java且类型安全的HTTP客户端，其最大的特性的是支持通过接口的方式发起HTTP请求。而spring-boot是使用最广泛的Java开发框架，但是Retrofit官方没有支持与spring-boot框架快速整合，因此我们开发了retrofit-spring-boot-starter。
retrofit-spring-boot-starter实现了Retrofit与spring-boot框架快速整合，并且支持了诸多功能增强，极大简化开发。
# 功能特性
[x] 自定义注入OkHttpClient [x] 注解式拦截器 [x] 连接池管理 [x] 日志打印 [x] 请求重试 [x] 错误解码器 [x] 全局拦截器 [x] 熔断降级 [x] 微服务之间的HTTP调用 [x] 调用适配器 [x] 数据转换器
# 快速使用
引入依赖
<dependency> <groupId>com.github.lianjiatech</groupId> <artifactId>retrofit-spring-boot-starter</artifactId> <version>2.2.2</version></dependency>定义http接口
@RetrofitClient(baseUrl = "${test.baseUrl}")public interface HttpApi {
@GET("person") Result<Person> getPerson(@Query("id") Long id);}注入使用
@Servicepublic class TestService {
@Autowired private HttpApi httpApi;
public void test() { // 通过httpApi发起http请求 }}# HTTP请求相关注解
配置项说明
retrofit: enable-response-call-adapter: true # 启用日志打印 enable-log: true # 连接池配置 pool: test1: max-idle-connections: 3 keep-alive-second: 100 test2: max-idle-connections: 5 keep-alive-second: 50 # 禁用void返回值类型 disable-void-return-type: false # 日志打印拦截器 logging-interceptor: com.github.lianjiatech.retrofit.spring.boot.interceptor.DefaultLoggingInterceptor # 请求重试拦截器 retry-interceptor: com.github.lianjiatech.retrofit.spring.boot.retry.DefaultRetryInterceptor # 全局转换器工厂 global-converter-factories: - retrofit2.converter.jackson.JacksonConverterFactory # 全局调用适配器工厂 global-call-adapter-factories: - com.github.lianjiatech.retrofit.spring.boot.core.BodyCallAdapterFactory - com.github.lianjiatech.retrofit.spring.boot.core.ResponseCallAdapterFactory # 是否启用熔断降级 enable-degrade: true # 熔断降级实现方式 degrade-type: sentinel # 熔断资源名称解析器 resource-name-parser: com.github.lianjiatech.retrofit.spring.boot.degrade.DefaultResourceNameParser# 高级功能
自定义注入OkHttpClient
@RetrofitClient(baseUrl = "http://ke.com")public interface HttpApi3 {
@OkHttpClientBuilder static OkHttpClient.Builder okhttpClientBuilder() { return new OkHttpClient.Builder() .connectTimeout(1, TimeUnit.SECONDS) .readTimeout(1, TimeUnit.SECONDS) .writeTimeout(1, TimeUnit.SECONDS);
}
@GET Result<Person> getPerson(@Url String url, @Query("id") Long id);}方法必须使用@OkHttpClientBuilder注解标记！
注解式拦截器
继承BasePathMatchInterceptor编写拦截处理器； 接口上使用@Intercept进行标注。如需配置多个拦截器，在接口上标注多个@Intercept注解即可！
下面以_给指定请求的url后面拼接timestamp时间戳_为例，介绍下如何使用注解式拦截器。
继承BasePathMatchInterceptor编写拦截处理器
@Componentpublic class TimeStampInterceptor extends BasePathMatchInterceptor {
@Override public Response doIntercept(Chain chain) throws IOException { Request request = chain.request(); HttpUrl url = request.url(); long timestamp = System.currentTimeMillis(); HttpUrl newUrl = url.newBuilder() .addQueryParameter("timestamp", String.valueOf(timestamp)) .build(); Request newRequest = request.newBuilder() .url(newUrl) .build(); return chain.proceed(newRequest); }}接口上使用@Intercept进行标注
@RetrofitClient(baseUrl = "${test.baseUrl}")@Intercept(handler = TimeStampInterceptor.class, include = {"/api/**"}, exclude = "/api/test/savePerson")public interface HttpApi {
@GET("person") Result<Person> getPerson(@Query("id") Long id);
@POST("savePerson") Result<Person> savePerson(@Body Person person);}扩展注解式拦截器
自定义拦截注解 继承BasePathMatchInterceptor编写拦截处理器 接口上使用自定义拦截注解；
例如我们需要在请求头里面动态加入accessKeyId、accessKeySecret签名信息才能正常发起http请求，这个时候可以自定义一个加签拦截器注解@Sign来实现。下面以自定义@Sign拦截注解为例进行说明。
自定义@Sign注解
@Retention(RetentionPolicy.RUNTIME)@Target(ElementType.TYPE)@Documented@InterceptMarkpublic @interface Sign { /** * 密钥key * 支持占位符形式配置。 * * @return */ String accessKeyId();
/** * 密钥 * 支持占位符形式配置。 * * @return */ String accessKeySecret();
/** * 拦截器匹配路径 * * @return */ String[] include() default {"/**"};
/** * 拦截器排除匹配，排除指定路径拦截 * * @return */ String[] exclude() default {};
/** * 处理该注解的拦截器类 * 优先从spring容器获取对应的Bean，如果获取不到，则使用反射创建一个！ * * @return */ Class<? extends BasePathMatchInterceptor> handler() default SignInterceptor.class;}自定义拦截注解必须使用@InterceptMark标记。 注解中必须包括include()、exclude()、handler()属性信息。
实现SignInterceptor
@Componentpublic class SignInterceptor extends BasePathMatchInterceptor {
private String accessKeyId;
private String accessKeySecret;
public void setAccessKeyId(String accessKeyId) { this.accessKeyId = accessKeyId; }
public void setAccessKeySecret(String accessKeySecret) { this.accessKeySecret = accessKeySecret; }
@Override public Response doIntercept(Chain chain) throws IOException { Request request = chain.request(); Request newReq = request.newBuilder() .addHeader("accessKeyId", accessKeyId) .addHeader("accessKeySecret", accessKeySecret) .build(); return chain.proceed(newReq); }}接口上使用@Sign
@RetrofitClient(baseUrl = "${test.baseUrl}")@Sign(accessKeyId = "${test.accessKeyId}", accessKeySecret = "${test.accessKeySecret}", exclude = {"/api/test/person"})public interface HttpApi {
@GET("person") Result<Person> getPerson(@Query("id") Long id);
@POST("savePerson") Result<Person> savePerson(@Body Person person);}连接池管理
1.配置连接池。
retrofit:# 连接池配置pool: test1: max-idle-connections: 3 keep-alive-second: 100 test2: max-idle-connections: 5 keep-alive-second: 502.通过@RetrofitClient的poolName属性来指定使用的连接池。
@RetrofitClient(baseUrl = "${test.baseUrl}", poolName="test1")public interface HttpApi {
@GET("person")Result<Person> getPerson(@Query("id") Long id);}日志打印
针对每个接口，可以通过@RetrofitClient的enableLog控制是否开启，通过logLevel和logStrategy，可以指定每个接口的日志打印级别以及日志打印策略。retrofit-spring-boot-starter支持了5种日志打印级别(ERROR, WARN, INFO, DEBUG, TRACE)，默认INFO；支持了4种日志打印策略（NONE, BASIC, HEADERS, BODY），默认BASIC。4种日志打印策略含义如下：
NONE：No logs. BASIC：Logs request and response lines. HEADERS：Logs request and response lines and their respective headers. BODY：Logs request and response lines and their respective headers and bodies (if present).
retrofit-spring-boot-starter默认使用了DefaultLoggingInterceptor执行真正的日志打印功能，其底层就是okhttp原生的HttpLoggingInterceptor。当然，你也可以自定义实现自己的日志打印拦截器，只需要继承BaseLoggingInterceptor（具体可以参考DefaultLoggingInterceptor的实现），然后在配置文件中进行相关配置即可。
retrofit: # 日志打印拦截器 logging-interceptor: com.github.lianjiatech.retrofit.spring.boot.interceptor.DefaultLoggingInterceptor请求重试
retrofit-spring-boot-starter支持请求重试功能，只需要在接口或者方法上加上@Retry注解即可。@Retry支持重试次数maxRetries、重试时间间隔intervalMs以及重试规则retryRules配置。重试规则支持三种配置：
RESPONSE_STATUS_NOT_2XX：响应状态码不是2xx时执行重试； OCCUR_IO_EXCEPTION：发生IO异常时执行重试； OCCUR_EXCEPTION：发生任意异常时执行重试；
默认响应状态码不是2xx或者发生IO异常时自动进行重试。需要的话，你也可以继承BaseRetryInterceptor实现自己的请求重试拦截器，然后将其配置上去。
retrofit: # 请求重试拦截器 retry-interceptor: com.github.lianjiatech.retrofit.spring.boot.retry.DefaultRetryInterceptor错误解码器
在HTTP发生请求错误(包括发生异常或者响应数据不符合预期)的时候，错误解码器可将HTTP相关信息解码到自定义异常中。你可以在@RetrofitClient注解的errorDecoder()指定当前接口的错误解码器，自定义错误解码器需要实现ErrorDecoder接口：
/** * 错误解码器。ErrorDecoder. * 当请求发生异常或者收到无效响应结果的时候，将HTTP相关信息解码到异常中，无效响应由业务自己判断 * * When an exception occurs in the request or an invalid response result is received, the HTTP related information is decoded into the exception, * and the invalid response is determined by the business itself. * * @author 陈添明 */public interface ErrorDecoder {
/** * 当无效响应的时候，将HTTP信息解码到异常中，无效响应由业务自行判断。 * When the response is invalid, decode the HTTP information into the exception, invalid response is determined by business. * * @param request request * @param response response * @return If it returns null, the processing is ignored and the processing continues with the original response. */ default RuntimeException invalidRespDecode(Request request, Response response) { if (!response.isSuccessful()) { throw RetrofitException.errorStatus(request, response); } return null; }
/** * 当请求发生IO异常时，将HTTP信息解码到异常中。 * When an IO exception occurs in the request, the HTTP information is decoded into the exception. * * @param request request * @param cause IOException * @return RuntimeException */ default RuntimeException ioExceptionDecode(Request request, IOException cause) { return RetrofitException.errorExecuting(request, cause); }
/** * 当请求发生除IO异常之外的其它异常时，将HTTP信息解码到异常中。 * When the request has an exception other than the IO exception, the HTTP information is decoded into the exception. * * @param request request * @param cause Exception * @return RuntimeException */ default RuntimeException exceptionDecode(Request request, Exception cause) { return RetrofitException.errorUnknown(request, cause); }
}# 全局拦截器
全局应用拦截器
@Componentpublic class SourceInterceptor extends BaseGlobalInterceptor { @Override public Response doIntercept(Chain chain) throws IOException { Request request = chain.request(); Request newReq = request.newBuilder() .addHeader("source", "test") .build(); return chain.proceed(newReq); }}全局网络拦截器
熔断降级
retrofit-spring-boot-starter支持熔断降级功能，底层基于Sentinel实现。具体来说，支持了熔断资源自发现和注解式降级规则配置。如需使用熔断降级，只需要进行以下操作即可：
1. 开启熔断降级功能
retrofit: # 是否启用熔断降级 enable-degrade: true # 熔断降级实现方式(目前仅支持Sentinel) degrade-type: sentinel # 资源名称解析器 resource-name-parser: com.github.lianjiatech.retrofit.spring.boot.degrade.DefaultResourceNameParser资源名称解析器用于实现用户自定义资源名称，默认配置是DefaultResourceNameParser，对应的资源名称格式为HTTP_OUT:GET:http://localhost:8080/api/degrade/test。用户可以继承BaseResourceNameParser类实现自己的资源名称解析器。
另外，由于熔断降级功能是可选的，因此启用熔断降级需要用户自行引入Sentinel依赖：
<dependency> <groupId>com.alibaba.csp</groupId> <artifactId>sentinel-core</artifactId> <version>1.6.3</version></dependency>2. 配置降级规则（可选）
@Retention(RetentionPolicy.RUNTIME)@Target({ElementType.METHOD, ElementType.TYPE})@Documentedpublic @interface Degrade {
/** * RT threshold or exception ratio threshold count. */ double count();
/** * Degrade recover timeout (in seconds) when degradation occurs. */ int timeWindow() default 5;
/** * Degrade strategy (0: average RT, 1: exception ratio). */ DegradeStrategy degradeStrategy() default DegradeStrategy.AVERAGE_RT;}如果应用项目已支持通过配置中心配置降级规则，可忽略注解式配置方式。
3. @RetrofitClient设置fallback或者fallbackFactory (可选)
fallbackFactory相对于fallback，主要差别在于能够感知每次熔断的异常原因(cause)。参考示例如下：
@Slf4j@Servicepublic class HttpDegradeFallback implements HttpDegradeApi {
@Override public Result<Integer> test() { Result<Integer> fallback = new Result<>(); fallback.setCode(100) .setMsg("fallback") .setBody(1000000); return fallback; }}
@Slf4j@Servicepublic class HttpDegradeFallbackFactory implements FallbackFactory<HttpDegradeApi> {
/** * Returns an instance of the fallback appropriate for the given cause * * @param cause fallback cause * @return 实现了retrofit接口的实例。an instance that implements the retrofit interface. */ @Override public HttpDegradeApi create(Throwable cause) { log.error("触发熔断了! ", cause.getMessage(), cause); return new HttpDegradeApi() { @Override public Result<Integer> test() { Result<Integer> fallback = new Result<>(); fallback.setCode(100) .setMsg("fallback") .setBody(1000000); return fallback; } }}# 微服务之间的HTTP调用
配置ServiceInstanceChooser为Spring容器Bean
用户可以自行实现ServiceInstanceChooser接口，完成服务实例的选取逻辑，并将其配置成Spring容器的Bean。对于Spring Cloud应用，retrofit-spring-boot-starter提供了SpringCloudServiceInstanceChooser实现，用户只需将其配置成Spring的Bean即可。@Bean@Autowiredpublic ServiceInstanceChooser serviceInstanceChooser(LoadBalancerClient loadBalancerClient) { return new SpringCloudServiceInstanceChooser(loadBalancerClient);}
使用@Retrofit的serviceId和path属性，可以实现微服务之间的HTTP调用@RetrofitClient(serviceId = "${jy-helicarrier-api.serviceId}", path = "/m/count", errorDecoder = HelicarrierErrorDecoder.class)@Retrypublic interface ApiCountService {
}调用适配器和数据转码器
调用适配器
1.BodyCallAdapterFactory
默认启用，可通过配置retrofit.enable-body-call-adapter=false关闭
同步执行http请求，将响应体内容适配成接口方法的返回值类型实例。
除了Retrofit.Call<T>、Retrofit.Response<T>、java.util.concurrent.CompletableFuture<T>之外，其它返回类型都可以使用该适配器。
2.ResponseCallAdapterFactory
默认启用，可通过配置retrofit.enable-response-call-adapter=false关闭
同步执行http请求，将响应体内容适配成Retrofit.Response<T>返回。
如果方法的返回值类型为Retrofit.Response<T>，则可以使用该适配器。
Retrofit自动根据方法返回值类型选用对应的CallAdapterFactory执行适配处理！加上Retrofit默认的CallAdapterFactory，可支持多种形式的方法返回值类型：
Call<T>: 不执行适配处理，直接返回Call<T>对象 CompletableFuture<T>: 将响应体内容适配成CompletableFuture<T>对象返回 Void: 不关注返回类型可以使用Void。如果http状态码不是2xx，直接抛错！ Response<T>: 将响应内容适配成Response<T>对象返回 其他任意Java类型：将响应体内容适配成一个对应的Java类型对象返回，如果http状态码不是2xx，直接抛错！
/** * Call<T> * 不执行适配处理，直接返回Call<T>对象 * @param id * @return */ @GET("person") Call<Result<Person>> getPersonCall(@Query("id") Long id);
/** * CompletableFuture<T> * 将响应体内容适配成CompletableFuture<T>对象返回 * @param id * @return */ @GET("person") CompletableFuture<Result<Person>> getPersonCompletableFuture(@Query("id") Long id);
/** * Void * 不关注返回类型可以使用Void。如果http状态码不是2xx，直接抛错！ * @param id * @return */ @GET("person") Void getPersonVoid(@Query("id") Long id);
/** * Response<T> * 将响应内容适配成Response<T>对象返回 * @param id * @return */ @GET("person") Response<Result<Person>> getPersonResponse(@Query("id") Long id);
/** * 其他任意Java类型 * 将响应体内容适配成一个对应的Java类型对象返回，如果http状态码不是2xx，直接抛错！ * @param id * @return */ @GET("person") Result<Person> getPerson(@Query("id") Long id);retrofit: # 全局调用适配器工厂 global-call-adapter-factories: - com.github.lianjiatech.retrofit.spring.boot.core.BodyCallAdapterFactory - com.github.lianjiatech.retrofit.spring.boot.core.ResponseCallAdapterFactory针对每个Java接口，还可以通过@RetrofitClient注解的callAdapterFactories()指定当前接口采用的CallAdapter.Factory，指定的工厂实例依然优先从Spring容器获取。
注意：如果CallAdapter.Factory没有public的无参构造器，请手动将其配置成Spring容器的Bean对象！
数据转码器
Gson: com.squareup.Retrofit:converter-gson Jackson: com.squareup.Retrofit:converter-jackson Moshi: com.squareup.Retrofit:converter-moshi Protobuf: com.squareup.Retrofit:converter-protobuf Wire: com.squareup.Retrofit:converter-wire Simple XML: com.squareup.Retrofit:converter-simplexml JAXB: com.squareup.retrofit2:converter-jaxb
retrofit-spring-boot-starter支持通过retrofit.global-converter-factories配置全局数据转换器工厂，转换器工厂实例优先从Spring容器获取，如果没有获取到，则反射创建。默认的全局数据转换器工厂是retrofit2.converter.jackson.JacksonConverterFactory，你可以直接通过spring.jackson.*配置jackson序列化规则，配置可参考Customize the Jackson ObjectMapper！
retrofit: # 全局转换器工厂 global-converter-factories: - retrofit2.converter.jackson.JacksonConverterFactory注意：如果Converter.Factory没有public的无参构造器，请手动将其配置成Spring容器的Bean对象！